Update composer/spdx-licenses to 1.4.0 and mediawiki/mediawiki-codesniffer to 21.0.0

[lhc/web/wiklou.git] / includes / parser / ParserOptions.php

diff --git a/includes/parser/ParserOptions.php b/includes/parser/ParserOptions.php
index 5959281..e4b064e 100644 (file)
--- a/includes/parser/ParserOptions.php
+++ b/includes/parser/ParserOptions.php
@@ -41,6 +41,13 @@ use Wikimedia\ScopedCallback;
  */
 class ParserOptions {
 
+       /**
+        * Flag indicating that newCanonical() accepts an IContextSource or the string 'canonical', for
+        * back-compat checks from extensions.
+        * @since 1.32
+        */
+       const HAS_NEWCANONICAL_FROM_CONTEXT = 1;
+
        /**
         * Default values for all options that are relevant for caching.
         * @see self::getDefaults()
@@ -659,7 +666,7 @@ class ParserOptions {
        /**
         * Get the user language used by the parser for this page and split the parser cache.
         *
-        * @warning: Calling this causes the parser cache to be fragmented by user language!
+        * @warning Calling this causes the parser cache to be fragmented by user language!
         * To avoid cache fragmentation, output should not depend on the user language.
         * Use Parser::getFunctionLang() or Parser::getTargetLanguage() instead!
         *
@@ -680,7 +687,7 @@ class ParserOptions {
        /**
         * Same as getUserLangObj() but returns a string instead.
         *
-        * @warning: Calling this causes the parser cache to be fragmented by user language!
+        * @warning Calling this causes the parser cache to be fragmented by user language!
         * To avoid cache fragmentation, output should not depend on the user language.
         * Use Parser::getFunctionLang() or Parser::getTargetLanguage() instead!
         *
@@ -930,10 +937,9 @@ class ParserOptions {
 
        /**
         * @warning For interaction with the parser cache, use
-        *  WikiPage::makeParserOptions(), ContentHandler::makeParserOptions(), or
-        *  ParserOptions::newCanonical() instead.
-        * @param User $user
-        * @param Language $lang
+        *  WikiPage::makeParserOptions() or ParserOptions::newCanonical() instead.
+        * @param User|null $user
+        * @param Language|null $lang
         */
        public function __construct( $user = null, $lang = null ) {
                if ( $user === null ) {
@@ -957,8 +963,7 @@ class ParserOptions {
        /**
         * Get a ParserOptions object for an anonymous user
         * @warning For interaction with the parser cache, use
-        *  WikiPage::makeParserOptions(), ContentHandler::makeParserOptions(), or
-        *  ParserOptions::newCanonical() instead.
+        *  WikiPage::makeParserOptions() or ParserOptions::newCanonical() instead.
         * @since 1.27
         * @return ParserOptions
         */
@@ -972,8 +977,7 @@ class ParserOptions {
         * Language will be taken from $wgLang.
         *
         * @warning For interaction with the parser cache, use
-        *  WikiPage::makeParserOptions(), ContentHandler::makeParserOptions(), or
-        *  ParserOptions::newCanonical() instead.
+        *  WikiPage::makeParserOptions() or ParserOptions::newCanonical() instead.
         * @param User $user
         * @return ParserOptions
         */
@@ -985,8 +989,7 @@ class ParserOptions {
         * Get a ParserOptions object from a given user and language
         *
         * @warning For interaction with the parser cache, use
-        *  WikiPage::makeParserOptions(), ContentHandler::makeParserOptions(), or
-        *  ParserOptions::newCanonical() instead.
+        *  WikiPage::makeParserOptions() or ParserOptions::newCanonical() instead.
         * @param User $user
         * @param Language $lang
         * @return ParserOptions
@@ -999,8 +1002,7 @@ class ParserOptions {
         * Get a ParserOptions object from a IContextSource object
         *
         * @warning For interaction with the parser cache, use
-        *  WikiPage::makeParserOptions(), ContentHandler::makeParserOptions(), or
-        *  ParserOptions::newCanonical() instead.
+        *  WikiPage::makeParserOptions() or ParserOptions::newCanonical() instead.
         * @param IContextSource $context
         * @return ParserOptions
         */
@@ -1015,12 +1017,29 @@ class ParserOptions {
         * different from the canonical values used for caching.
         *
         * @since 1.30
-        * @param User|null $user
-        * @param Language|StubObject|null $lang
+        * @since 1.32 Added string and IContextSource as options for the first parameter
+        * @param IContextSource|string|User|null $context
+        *  - If an IContextSource, the options are initialized based on the source's User and Language.
+        *  - If the string 'canonical', the options are initialized with an anonymous user and
+        *    $wgContLang.
+        *  - If a User or null, the options are initialized for that User (or $wgUser if null).
+        *    'userlang' is taken from the $userLang parameter, defaulting to $wgLang if that is null.
+        * @param Language|StubObject|null $userLang (see above)
         * @return ParserOptions
         */
-       public static function newCanonical( User $user = null, $lang = null ) {
-               $ret = new ParserOptions( $user, $lang );
+       public static function newCanonical( $context = null, $userLang = null ) {
+               if ( $context instanceof IContextSource ) {
+                       $ret = self::newFromContext( $context );
+               } elseif ( $context === 'canonical' ) {
+                       $ret = self::newFromAnon();
+               } elseif ( $context instanceof User || $context === null ) {
+                       $ret = new self( $context, $userLang );
+               } else {
+                       throw new InvalidArgumentException(
+                               '$context must be an IContextSource, the string "canonical", a User, or null'
+                       );
+               }
+
                foreach ( self::getCanonicalOverrides() as $k => $v ) {
                        $ret->setOption( $k, $v );
                }
@@ -1271,7 +1290,7 @@ class ParserOptions {
         *
         * @since 1.17
         * @param string[] $forOptions
-        * @param Title $title Used to get the content language of the page (since r97636)
+        * @param Title|null $title Used to get the content language of the page (since r97636)
         * @return string Page rendering hash
         */
        public function optionsHash( $forOptions, $title = null ) {